---
title: Troubleshooting
description: Common issues and solutions
---

<Callout title="Tip">
  Check out the list of [known issues and solutions](https://github.com/47ng/nuqs/issues/423).
</Callout>

## Pages router

Because the Next.js **pages router** is not available in an SSR context, this
hook will always return `null{:ts}` (or the default value if supplied) on SSR/SSG.

This limitation doesn't apply to the app router.

## Caveats

### Different parsers on the same key

Hooks are synced together on a per-key basis, so if you use different parsers
on the same key, the last state update will be propagated to all other hooks
using that key. It can lead to unexpected states like this:

```ts
const [int] = useQueryState('foo', parseAsInteger)
const [float, setFloat] = useQueryState('foo', parseAsFloat)

setFloat(1.234)

// `int` is now 1.234, instead of 1
```

We recommend you abstract a key/parser pair into a dedicated hook to avoid this,
and derive any desired state from the value:

```ts
function useIntFloat() {
  const [float, setFloat] = useQueryState('foo', parseAsFloat)
  const int = Math.floor(float)
  return [{int, float}, setFloat] as const
}
```

## Client components need to be wrapped in a `<Suspense>` boundary

You may have encountered the following [error message](https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout)
from Next.js:

```
Missing Suspense boundary with useSearchParams
```

Components using hooks like `useQueryState` should be wrapped in `<Suspense>` when rendered within a page component. Adding the 'use client' directive to the page.tsx file is the immediate fix to get things working if you are defining components that use client-side features (like nuqs or React Hooks):

```tsx
'use client'

export default function Page() {
  return (
    <Suspense>
      <Client />
    </Suspense>
  )
}

function Client() {
  const [foo, setFoo] = useQueryState('foo')
  // ...
}
```

However, the steps below indicate the optimal approach to get better UX: separating server and client files (and moving client side code as low down the tree as possible to pre-render the outer shell).

The recommended approach is:

1. Keep page.tsx as a server component (no `'use client'{:ts}` directive)
2. Move client-side features into a separate client file.
3. Wrap the client component in a `<Suspense>` boundary.

